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BASIC-PLUS-2 
DOCUMENTATION SUPPLEMENT 


1.0 RELATED DOCUMENTATION 


This manual supplements the manual BAS/C on RSX-11M/M-PLUS Systems 
(Order No. AA-L338A-TC). Both manuals are included in the documentation set 
shipped to Tool Kit users who have ordered BASIC-PLUS-2. Also included in 
that set are the BAS/C Reference Manual (Order No. AA-L334A-TK) and the BA- 
SIC User’s Guide (Order No. AA-L335A-TK). See these three manuals for addi- 
tional information on BASIC and BASIC-PLUS-2 on RSX systems. The BAS/C 
Pocket Reference Guide (Order No. AV-L341A-TK), available separately, is use- 
ful for quick reference. 


For information on the current release of Professional Tool Kit BASIC-PLUS-2, 
its installation and known bugs, see the Professional Tool Kit BASIC-PLUS-2 
Installation Guide and Release Notes (Order No. AA-P104A-TK). 


2.0 PROFESSIONAL TOOL KIT BASIC-PLUS-2 


BASIC-PLUS-2 is a programming language that uses familiar words and math- 
ematical notations. With Tool Kit BASIC-PLUS-2 you can create applications on 
an RSX-11M/M-PLUS or VAX/VMS host system that run on the Professional 
Operating System (P/OS). This manual describes the differences between 
BASIC-PLUS-2 on RSX systems and Tool Kit BASIC-PLUS-2. 


The material here is intended for programmers experienced with BASIC- 
PLUS-2 on RSX systems. 
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3.0 DEVELOPMENT CYCLE 


The development cycle for Tool Kit BASIC-PLUS-2 applications (Figure 1) con- 
sists of the following steps: 


1. Write source program. 
2. Compile source program, creating object module file. 
L] Compile with /DEBUG to debug at run time. 
LI Compile without /DEBUG when program is error-free. 


3. Build command file and overlay descriptor language file. Edit command 
file and descriptor file as needed. 


4. Task build to create executable task image file. 


9. Write application installation file; move it and the task to the Profes- 
sional. 


6. Run task on the Professional. If desired, debug using REDIRECT com- 
mand and terminal attached to the Professional workstation. 


7. Run Application Diskette Builder when program is error-free, creating 
final diskette. 


The following sections present specific details of application development in 
Tool Kit BASIC-PLUS-2. For a complete description of each stage in Tool Kit 
application development, you should refer to the Too/ Kit User’s Guide. 


3.1 Writing the Source Program 


The BASIC-PLUS-2 source program can include external subroutine calls to ac- 
cess P/OS facilities from your program. The external subroutine calls are de- 
scribed in the Tool Kit User’s Guide and the CORE Graphics Library Manual. 
Facilities exist in the following areas: 


1. P/OS user interface support: the Tool Kit BASIC-PLUS-2 application 
has access to P/OS menu, help, message, and other system services. 
The ability to display error messages, status, on-line Help, and menus 
on the screen is provided through the P/OS Service Routines Library. 


2. Extended software functions: the Tool Kit BASIC-PLUS-2 application 
can invoke callable system services, such as PROSE (the P/OS text edi- 
tor) and the Communications Facility. 


P/OS facilities are accessed through the register 5 (R5) calling sequence with 
the BASIC-PLUS-2 CALL BY REF statement. 


3.1.1 Differences and Unsupported Features—Table 1 summarizes features 
that will influence your source code. Some operate differently than on RSX sys- 
tems, others are unsupported. Do not use the unsupported features listed here 
when you write an application using Tool Kit BASIC-PLUS-2. 


For more information on editing the command and overlay descriptor files, see 
Sections 3.5 and 3.6 of this supplement. For a complete list of Tool Kit BASIC- 
PLUS-2 error messages, See Section 4. 
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Figure 1 Tool Kit BASIC-PLUS-2 Development Cycle 
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Table 1 


Tool Kit BASIC-PLUS-2—lItems of Interest 


Feature 


Compiler Commands 
RUN 
LOAD 
BUILD 
BUILD/DUMP 
BUILD/NOSEQUENTIAL 
SET DUMP 
SET NOSEQUENTIAL 
Debugger Commands 
REDIRECT 


Error Messages 


Immediate Mode 
Magnetic Tape Operations 
RMS Support 
Statements 

CHAIN 


FSS$ Function 
EDIT$ 


Time Format 


3.2 Character Sets 


Please Note 


Not in the Tool Kit compiler. 

Not in the Tool Kit compiler. 

.CMD file must be edited. .ODL file may need to be edited. 
Unsupported. 

Unsupported for programs that do not access RMS files. 
Unsupported. 


Unsupported for programs that do not access RMS files. 


Allows debugging during application execution from a terminal 
attached to the Professional. Does not accept terminal device 
number. 


A subset of error messages for BASIC-PLUS-2 on RSX. You 
must press RESUME to continue after receiving error mes- 
sage. 


Not in Tool Kit compiler. 
Unsupported. 


Must not be removed from task image. 


Accepts installed task name, same as name in application in- 
stallation file (not file specification). 


Unsupported for named directories. 


Do not use any odd integer as argument to EDIT$ if the string 
to be operated on is an 8-bit character: high-order bit will be 
cleared. 


Twelve-hour AM/PM format unsupported. 


Tool Kit BASIC-PLUS-2 supports the DEC Multinational Character Set in string 
literals, comments, and DATA statements when you compile the application, 
and as input or output when you run the application on the Professional. (See 
the Terminal Subsystem Manual for a description of the DEC Multinational 


Character Set.) 


The compiler does not allow European alphabetics in variable names. 


Do not use any odd integer as the argument to EDIT$ if the string to be oper- 
ated on is an 8-bit character: the high-order bit will be cleared. 
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3.3 Compiling the Source Program 


When you install Tool Kit BASIC-PLUS-2 on your host system, you select the 
Extended Instruction Set (EIS) compiler, the Floating Point Unit (FPU) compiler, 
or both, as part of the installation process. Your choice should reflect the envi- 
ronment in which your applications will run. Floating Point hardware is optional 
on the Professional. Your host development system does not require an FPU to 
run the Tool Kit FPU compiler. Build your programs with the FPU compiler only 
if your applications will run‘on Professionals which have the Floating Point op- 
tion. 


To invoke the EIS compiler on RSX-11M/11M-PLUS, type: 
>RUN $PBE 

To invoke the FPU compiler, type: 
>RUN $PBF 

To invoke the EIS compiler on VAX/VMS, use the command: 
$ RUN SYS$SYSTEM:PBE 

To invoke the FPU compiler, use the command: 
$ RUN SYS$SYSTEM: PBF 


Compile your source program using the BASIC-PLUS-2 COMPILE command. 
The compiler will check each line of the source program for errors, returning an 
appropriate message if an error is found. You can then correct the program as 
necessary and recompile it. Program compilation produces an object module 
file (file. OBJ) that can be task built on the host system. 


BASIC-PLUS-2 has its own debugger. To use the debugger with your applica- 
tion, compile your source program using the /DEBUG qualifier. When you ex- 
ecute the application on the Professional, you can issue commands to the 
debugger to control and monitor application execution. 


3.4 Generating the Command and Descriptor Files 


After compiling the program, use the BASIC-PLUS-2 BUILD command to gen- 
erate a command file (file;CMD) and overlay descriptor file (file;ODL) for your 
application. The Professional Application Builder (PAB) uses these files to de- 
fine how libraries are referenced, and to specify special-purpose buffers, logical 
unit numbers (LUNs), and event flags (EFNs). 


You must edit the command file before you task build. You may also need to 
edit the overlay descriptor file. The following sections describe the information 
that must be contained in the command and overlay descriptor files. 
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3.4.1 Rebuilding an Application—If you are rebuilding an application to use 
the FPU OTS, having first built it for the EIS OTS, you must change all occu- 
rences of PBE to PBF in the command and overlay descriptor files generated by 
the EIS compiler. You must also add the /FP switch to the task image output file 
specification in the command file. 


3.5 Editing the Command File 


You must edit the command file generated by the Tool Kit BASIC-PLUS-2 com- 
piler. 


A command file output by the Tool Kit BASIC-PLUS-2 EIS compiler for an appili- 
cation named “‘TEST1”’ would look like this: 


SYtTESTT/CP#SY=ETEST 17 MP 
UNITS = 15 

ASG = T1I:13:15 

ASG: = SYso'Gs/7+S29. 10211 t2 
EXTTSK= 952 

CLSTR=PBESML ,RMSRES:RO 

// 


The command file automatically references the language OTS, clustered with 
RMS. However, you must edit the command file to include the P/OS Service 
Routines library, or you will get undefined symbols when you task build. You 
should also edit the command file if you want to reference any libraries other 
than the language OTS and RMS, such as FMS-11 or Graphics. 


You must make the following edits to your .CMD file: 
1. Task Name —The command file must assign a task name to the task 
image. The task name is assigned with a command line of the form: 
TASK = task-name 
The value task-name is a 1- to 6—character name identifying the task. 
The task-name is the installed name of the task. 


2. Clusterable Libraries —You must edit the command file to reference 
the POSRES library. List all referenced clusterable libraries on the line 
beginning “‘CLSTR”’. Note that the default library must be the Tool Kit 
BASIC-PLUS-2 OTS: you must list this library first. After it, list libraries 
in the order of greatest use. For example: 


CLSTR = PBESML,RMSRES,POSRES:RO 
This line identifies the BASIC-PLUS-2 EIS OTS (PBESML) as the de- 


fault library, and RMS and POSRES as referenced libraries, with RMS 
being referenced more often than POSRES. All libraries are read-only. 


3. Additional Logical Units —Since P/OS will require additional logical 
units, change the UNITS number in the second line to 18: 


UTIs: = 48 
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Extend Section Commands.—If your application uses P/OS user inter- 
face services in the POSRES library, allocate buffer space with extend 
section (EXTSCT) commands in the command file. See the section on 
task building in Chapter 2 of the Too/ Kit User’s Guide for instructions 
on calculating buffer sizes for P/OS user interface services. 


Logical Unit Numbers.—P/OS user interface services require logical 
unit numbers (LUNs) to perform file |/O to menu, help, and message 
definition files. LUN assignments for P/OS I/O can be made with global 
definition commands (GBLDEF) in the command file. In assigning LUNs, 
remember to account for LUNs needed by the BASIC-PLUS-2 OTS. 
You must include the LUN for BASIC-PLUS-2 OTS messages: 


GBLDEF = MS$LUN:16 ; message frame file 


If one type of P/OS service is never used, such as help services, specify 


0 in the global definition line for message files. Do not omit any global 
definition lines. 


Event Flags.—P/OS user interface routines also require an event flag 
(EFN) to perform terminal I/O. The event flag assignment must not con- 
flict with event flag assignments made for other purposes by the appli- 
cation. Language OTS routines use DIGITAL reserved event flags (flags 
25-32). The event flag assigned with the TT$EFN line should not be a 
DIGITAL reserved flag. 


Note: The assign (ASG) commands and UNITS commands list decimal num- 
bers. Extend section (EXTSCT) and global definition (GBLDEF) lines specify 
octal numbers. 


The following list shows the required extend section and global definition lines 
that are added just below the ‘“‘CLSTR’” line in the command file. The values for 
the extend section lines (EXTSCT) are calculated for the largest possible frame 
of each type. That is, if every field on a menu, help, and message frame were 
filled in with the maximum amount of data, the respective buffers must be allo- 
cated the sizes shown. 


EXTSCT 
EXTSCT 
EXTSCT 
EXTSCT 
EXTSCT 


GBLDEF 
GBLDEF 
GBLDEF 
GBLDEF 
GBLDEF 
GBLDEF 


; DEFINE BUFFER SIZES 


= MN$BUF : 4540 ; static single-choice menu 

= DM$BUF : 4540 ; dynamic single-choice menu 

= MM$BUF: 1000 s multi-choice menu 

= HL$BUF :3410 ; help text or help menu 

= FL$BUF :4310 ; file selection/specification 
- for OLDFIL and NEWFIL routine 
; DEFINE LUN ASSIGNMENTS 

= MN$LUN: 20 ; menu frame file 

= HL$LUN:21 ; help frame file 

= MS$LUN: 16 ; message frame file 

= TT$LUN: 15 ; terminal 1/0 

= TT$EFN: 1 ; terminal I/0 event flag 

= WC$LUN:22 ; directory searches for OLDFIL and NEWFIL 


; routine or callable print services 


The edited command file for TEST1 would look something like this (new or 
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edited lines are shaded) 


TES lAgMe 


SY 


TEST1/CP#=SY 


oO: 


3 


8 


if 


6 


SY<5 
952 


on 
peo) 
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Bee 
ee 


— 


as 
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1 
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le 


tor Fi 


ip 


3.6 Editing the Overlay Descr 
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11 
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3 
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See BASIC on RSX- 
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Systems for information on editing BASIC-PLUS-2 .ODL files. 
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ject | 
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lf you want to reference any Tool K 


11M/M- 


le. 


iptor f 
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Use the Professional Application Builder (PAB) to create an application task im- 
age (file. TSK). See the Too/ Kit User’s Guide for complete information on Pro- 


3.7 Building the P/OS Task Images 
fessional Application Builder commands. 
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3.8 Debugging During Execution 


Use the BASIC-PLUS-2 debugger to debug the program. (See your BASIC doc- 
umentation for more information on the BASIC-PLUS-2 debugger.) In addition, 
when you execute a task on the Professional, you can also connect a terminal 
to the printer port on the Professional for debugging. (See the Too/ Kit User’s 
Guide for details.) Use the Tool Kit BASIC-PLUS-2 REDIRECT command to dis- 
play debugger I/O and issue debugger commands on that terminal. Input is ac- 
cepted from and output goes to the printer port. Note that the REDIRECT 
command does not accept a terminal device number. All other I/O, including 
graphics or forms, will remain unaffected. 


4.0 TOOL KIT BASIC-PLUS-2 RUN-TIME ERROR MESSAGES 
Tool Kit BASIC-PLUS-2 run-time error messages are a subset of BASIC- 
PLUS-2 run-time error messages on RSX systems. The Tool Kit BASIC-PLUS-2 
run-time error messages are preceded by a number to help you report the error. 
If you use ERT$ to reference an error not in the Tool Kit BASIC-PLUS-2 subset, 
ERT$ will return the following message: 

Can’t access LB:{1,2]BASIC2.ERR or can’t find frame <id> 


Frame <id> will identify the error number of the ERT$ you tried to reference. 


If the debugger is not present, the following notice will appear on the screen 
after the error message is displayed: 


Please write down the above message -- press RESUME to contint 


You must press the RESUME key to clear the screen and continue. 


Table 2 
Tool Kit BASIC-PLUS-2 Error Messages 


Number Text 


—"s 


?Bad directory for device 

? Illegal file name 

?Account or device in use 
?No room for user on device 
?Can't find file or account 
?Not a valid device 

?1/O channel already open 


?Device not available 


Oo oa nN Do oO FSF W PP 


?1/O channel not open 


—b 
© 


?Protection violation 
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Table 2 Continued 
Tool Kit BASIC-PLUS-2 Error Messages 


Number Text 
11 ?End of file on device 
12 ?Fatal system |/O failure 
13 ?User data error on device 
14 ?Device hung or write locked 
15 ?Keyboard wait exhausted 
19 ?Disk block is interlocked 
28 ?Programmable ae trap 
31 ?\llegal byte count for I/O 
34 ?Reserved instruction trap 
35 ?Memory management violation 
43 ?Virtual array not on disk 
44 ? Matrix or array too big 
45 ?Virtual array not yet open 
46 ?\llegal 1/O Channel 
47 ?Line too long 
48 %Floating point error 
50 %Data format error 
oR “elnteger error 
52 ? illegal number 
53 %lllegal argument in LOG 
54 “%ilmaginary square roots 
55 ?Subscript out of range 
56 ?Can't invert matrix 
5/ ?Out of data 
58 ?0N statement out of range 
59 ?Not enough data in record 
60 ?integer overflow, FOR loop 
61 %Division by 0 
63 ?FIELD overflows buffer 
64 ?Not arandom access device 
72 RETURN without GOSUB 
73 ?FNEND without function call 
88 ?Arguments don't match 
89 ?Too many arguments 
or ?Too few arguments 

104 ?RESUME and no error 


105 ?Redimensioned array 


Table 2 Continued 
Tool Kit BASIC-PLUS-2 Error Messages 
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Number 


116 
126 
127 
130 
131 
132 
133 
134 
135 
136 
137 
138 
139 
140 
144 
142 
143 
144 
145 
147 
148 
149 
150 
151 
152 
153 
154 
155 
156 
157 
158 
159 
160 
161 
162 
164 
166 


Text 


?PRINT-USING format error 
?Maximum memory exceeded 
%SCALE factor interlock 
?Key not changeable 

?No current record 

?Record has been deleted 
?\llegal usage for device 
?Duplicate key detected 
?\llegal usage 

?\llegal or illogical access 

? Illegal key attributes 

?File is locked 

? Invalid file options 

?index not initialized 

?\llegal operation 

?\Ilegal record on file 

?Bad record identifier 

? Invalid key of reference 

?Key size too large 

?RECORD number exceeds maximum 
?Bad RECORDSIZE value on OPEN 
?Not at end of file 

?No primary key specified 
?Key field beyond end of record 
?\llogical record accessing 
?Record already exists 
?Record/bucket locked 
?Record not found 

?Size of record invalid 
?Record on file too big 
?Primary key out of sequence 
?Key larger than record 

?File attributes not matched 
?Move overflows buffer 
?Cannot open file 

?Terminal format file required 


?Negative fill or string length 


12 TOOL KIT BASIC-PLUS-2 SUPPLEMENT 


Table 2 Continued 
Tool Kit BASIC-PLUS-2 Error Messages 


Number 


167 
168 
170 
171 
173 
180 
183 
184 
185 
186 
246 
247 
248 
250 
251 
252 
253 


Text 


Illegal record format 

Illegal ALLOW clause 

?Index not fully optimized 
?RRV not fully updated 
?Invalid RFA field 

?No support for op in task 

? REMAP overflows buffer 
%Unaligned REMAP variable 
?RECORDSIZE overflows MAP buffer 
?improper error handling 
?Error trap needs RESUME 
?\llegal RESUME to subroutine 
? illegal return from subroutine 
?Not implemented 

?Recursive subroutine call 
?FILE ACP failure 


?Directive error 


Please cut along this line. 
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